Skip to main content

Documentation

Welcome to the Cegid Talentsoft Recruiting for Job advertising service APIs!

Introduction​

Thanks to Job advertising service Apis , customers can build their own career website based on multi-location feature, set multiple locations for one vacancy and then publish it instead of duplicating it per location each time.

These APIs represent the several actions that a jobseeker (or an employee) can perform through a Cegid-Talentsoft Recruiting JAS Career website Once the multilocation feature Activated, a new field "locations" is available, allowing recruiters to select multiple locations for their vacancies. This field uses Azure map geolocation services.

Functional requirements​

JobAd is the main business object of JAS, it represents the publication of a joboffer. Once a vacancy with multiple locations is published on the JAS career website , jobads are generated, one per language per one location,

It may be searchable by its reference, description, properties and its location.

It aggregates information describing the jobOffer

A Brand is the set of API used later to build the career website, and to generate the Jobboard URL. It is created and managed via Recruiting Back Office by our Super Admin , we can add different languages to brand. A brand can only have one language by default. Not possible to Edit the Language by default , Brand's name and Id.

APIs specifications by topic:​

Jobseeker​

This set of endpoints is dedicated to JobSeekers. It exposes features from a job seeker perspective: search for job ads and apply to job ads.

  • In order to access the APIs, you should target the Jobadboard through its URL along with: <pre><code class="lang-html">http://[JOBJoard-url]/<span class="typ">{brandId}/<span class="typ">api/jobseeker/v{number}/{endpoint}</span></code></pre>

  • In the previous example, number corresponds to the version of the API and endpoint to the action you are calling.

  • If the targeted Front Office site is secured (it uses HTTPS protocol), you should use https:// when calling any API endpoint.

Authorization​

  • In order to interact with the APIs, the application will need to be identified through a client_id and a client_secret.
  • If you are developing a website, don't forget to add your URL into the whitelisted domains.
  • All your calls to the APIs should send a Token (to identify your application).
  • To get a Token, visit the Authentication section.

Response and Request formats​

  • These APIs work only with JSON as their transport format.
  • All JSON properties are named in camel case starting by lower case (e.g. customFields).
  • Dates follow the ISO 8601 standard.

Implementation recommendations

The implementer must comply with Cegid’s general terms of use. In order to reduce the number of requests, please abide by the following recommendations:

Global:​

  • The number of API calls must be kept to a minimum.
  • Errors must be corrected.

Authentication:​

  • Request only one token for a given user session. Avoid requesting a new token between each API call and only request a new token when the current one has expired (20-minute duration).
  • The token request should be made by the server. If an api/token call is made from a browser, then the client_id & client_secret are shared with the end user, which is not recommended for security reasons. The token should therefore be obtained from a backchannel request.

Retrieving Jobads​

  • Jobads endpoints are only designed for performing searches, and not for exports.

  • It is recommended to avoid making calls with a high count parameter.

  • Implementation of this behaviour may lead to an API key rate limit or a ban on a given IP address.

Error codes​

Error messages of type 400 (Bad Request) and 409 (Conflict) return a standardized error code. This code is embedded in the header "X-TS-ErrorCode" of the Http response.

Cinematics

Cinematic of API calls to search Jobads and display one:​

  1. Retrieve a token “as an application” (grant_type=credentials): POST /auth/token
  2. Search for Jobads: GET /{brandId}/api/Jobseeker/v1/jobads
  3. Display one jobad: GET /{brandId}/api/Jobseeker/v1/jobads/[reference]
  4. Filter Jobads : GET /{brandId}/api/jobseeker/v1/jobads[?filter][&boundary][&field][&pagetoken][&sign][&limit]

Cinematic of API calls to apply without account:​

  1. Retrieve a token “as an application” (grant_type=credentials): POST /auth/token
  2. Create the application: POST {brandId}/api/jobseeker/v1/jobads/:reference/quickapplication

How to

How to retrieve a token​

  1. “As an application”:
    • POST /auth/token HTTP/1.1
    • Host: [jasDefaultBrandUrl]
    • Cache-Control: no-cache
    • Content-Type: application/x-www-form-urlencoded
client_id=[clientID]&client_secret=[clientSecret]&grant_type=client_credentials

How to search jobads by geolocation​

  1. Retrieve a token “as an application” (grant_type=credentials): POST /auth/token
  2. Search for vacancies with boundaries: GET /api/jobseeker/v1/jobads?filter=123&boundaries=[{"lon":40,"lat":40},{"lon":-40,"lat":40},{"lon":-40,"lat":-40},{"lon":40,"lat":-40}]&limit=1

Authorized file extensions​

doc, docx, pdf, txt, rtf, odt, html, jpg